home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / FROMUTS / TAR / ReadMe < prev    next >
Text File  |  1991-11-07  |  16KB  |  443 lines
  1. tar - tape archive, version 1.1o, written for the Archimedes by
  2.  
  3.                     Frank Lancaster, 7-Nov-1991
  4.  
  5. Bug reports and comments may be sent as e-mail to: fl@tools.uucp
  6. Paper Mail: Frank Lancaster
  7.             Tools GmbH
  8.             Kessenicher Str. 108
  9.             W-5300 Bonn 1
  10.             Federal Republic of Germany
  11.  
  12.  
  13. This programme is public domain. You may copy it freely, provided
  14. you do not charge ANYTHING for its distribution.
  15.  
  16.  
  17. Table of Contents
  18. -----------------
  19.  1. Introduction
  20.  2. Installation
  21.  3. Usage
  22.  4. Normal Files As Archives
  23.  5. Hard Disc Backup
  24.  6. Compression
  25.  7. The List File
  26.  8. UNIX Compatibility
  27.  9. Raw disc dumping
  28. 10. History
  29.  
  30.  
  31.  
  32. 1. Introduction
  33. ---------------
  34. This version of tar is derived from the UNIX tar utility. Its main use
  35. is as a hard disk backup programme. It also comes in very handy when
  36. transferring files from or to UNIX. The name "tape archive" is misleading but
  37. historical. On the Archimedes archives are ordinary files on any
  38. file-system (adfs, scsi, dosfs, etc.). Multiple disc archives are supported,
  39. now also as ordinary files. Disk archives in ADFS D/E/L or MS-DOS (double-
  40. sided, 9 sectors) format dumped to raw disks are supported.
  41.  
  42.  
  43.  
  44. 2. Installation
  45. ---------------
  46. If you have clib version 3.66, you can use the tar_clib and compr_clib
  47. versions of tar and compress.
  48. Before using the programme set the system variable "tar$scrap" to the
  49. name of a temporary scrap file which should only be used by tar,
  50. for example "adfs::4.$.tmp.scrap". The leaf name must not be longer than
  51. 8 characters, another 2 ("-Z") are added if compression is used.
  52. This file will only be used if compression is enabled.
  53. If compression is used tar requires the compress programme (included in
  54. this distribution), which handles compression and decompression. Normally
  55. this should be accessable via the system variable Run$Path, but you can
  56. customize the compression and decompression commands with the two system
  57. variables tar$compress and tar$decompress (see below "compression").
  58. The system variable tar$filetype is used as file type for tar files. If
  59. it is not set, file type FFD (data) is used.
  60.  
  61.  
  62.  
  63. 3. Usage
  64. --------
  65. The programme should be called from the command line interpreter as it
  66. requires parameters.
  67.  
  68. tar [-]Commands[Options] ARCHIVE [LIST] [BLKS] [LEN] [-C DIR] file1 file2 ...
  69.  
  70. Commands:
  71.      c           create a new archive
  72.      r           append files to end of archive
  73.      t           list the contents of an archive
  74.      x           extract files from an archive
  75.  
  76. Options:
  77.      b BLKS      blocking factor BLKS (block size = BLKS x 512 bytes)
  78.      e LENGTH    maximum length of extension to use in UNIX file names
  79.      f ARCHIVE   read/write archive from file ARCHIVE (mandatory)
  80.      i           ignore checksum errors and blocks of zeros (normally EOF)
  81.      l [LIST]    read list of files from file LIST or !tarlist as default
  82.      m           don't extract file modified time
  83.      p           convert '!' in RISC OS names to '.' in UNIX names
  84.      s           swap extension in filename
  85.      v           verbosely list what files we process
  86.      w           ask for confirmation
  87.      z           run files through compress
  88.      B           reblock as we read
  89.      C DIR       change to directory DIR
  90.      E           '.' in UNIX names will be converted to '_'
  91.      F           format disk in drive 0 (multiple volumes & E-format only)
  92.      M           use multiple volume archiving
  93.      O           do not prompt for confimation when formating or overwriting disks
  94.      Q           quit immediately if error occurs, do not prompt for action
  95.      S           swap extensions in whole path
  96.      T           file types appended to names as with RISC-OS NFS
  97.      U           UNIX archive (no Archimedes extensions)
  98.      Z           convert UNIX '.Z' to '-Z' when extracting
  99.  
  100.  
  101. You must specify an archive file on the command line with the 'f' option.
  102. The path names of the archived files are stored as specified on
  103. the command line. Using the 'v' (verbose) option will list the path names
  104. stored as the archive is created. Normally you shouldn't specify the absolute
  105. path names, as you may want to extract the files to an other directory.
  106.  
  107.  
  108.  
  109. 4. Normal Files As Archives
  110. ---------------------------
  111. Here the use of tar is identical to the UNIX usage. The file name of an
  112. archive must always be supplied with the 'f' option. To create an archive
  113. use the 'c' option:
  114.  
  115. tar cvf myarc file1 file2 file3
  116.  
  117. This will create an archive 'myarc' in the current directory which contains
  118. the files 'file1', 'file2' and 'file3'. I always recommend using the 'v'
  119. option with every command, this gives more information on what is happening.
  120.  
  121. You can use path names with the archives and files specified:
  122.  
  123. tar cvf adfs::4.tmp.myarc adfs::5.file1 adfs::4.src.file2
  124.  
  125. To list the contents of an archive use the 't' command:
  126.  
  127. tar tvf myarc
  128.  
  129. To extract files from an archive use the 'x' command:
  130.  
  131. tar xvf myarc
  132.  
  133. This command will extract all files in the archive. If you only want certain
  134. files, you can specify them after the archive name:
  135.  
  136. tar xvf myarc file1 file2
  137.  
  138.  
  139.  
  140. 5. Hard disc backup
  141. -------------------
  142. This actually isn't very different from normal archiving. The main difference
  143. is that archive files are of course written to floppy discs and that they
  144. can be split across several discs. The command:
  145.  
  146. tar cvMf :0.backup :4.*
  147.  
  148. will backup all files on the hard disk :4 onto floppy disk :0 in the
  149. file 'backup'. If the archive requires more than one floppy disc, you will
  150. be prompted for more discs, which will contain further files also called
  151. 'backup'. They contain a header which supplies identification of the disc
  152. number so that 'tar' will be able to determine the disc sequence when
  153. extracting.
  154.  
  155. It would be better to go to the root directory of the hard disc and to use
  156. the following command:
  157.  
  158. tar cvMf :0.backup *
  159.  
  160. This will store the path names without the drive name, so you could extract
  161. them onto a different hard disk.
  162.  
  163. The command:
  164.  
  165. tar tvf :0.backup
  166.  
  167. will list the contents of an archive on floppy disc :0. If the archive was
  168. split across several discs, tar will prompt for further discs when finished
  169. listing one.
  170.  
  171. The command:
  172.  
  173. tar xvf :0.backup
  174.  
  175. will extract all files on floppy disc :0 in the file 'backup'. If the file,
  176. which is being extracted, already exists, tar will overwrite it without any
  177. warning.
  178.  
  179.  
  180.  
  181. 6. Compression
  182. --------------
  183. With the 'z' option files can be compressed before being written to an archive.
  184. For compression the standard UNIX utility compress is used, also supplied with
  185. the tar programme. The system variable tar$scrap is used for temporary storage.
  186. If you are backing up a complete hard disc and have enough memory you should
  187. use a RAM disc for the scrap file, and the compress programme should also be
  188. copied onto the RAM disc. You can use different programmes for
  189. compression and decompression if you set the tar$compress and tar$decompress
  190. system variables. The default settings are:
  191.  
  192.   tar$compress          compress < %1 > %2
  193.   tar$decompress        compress -d < %1 > %2
  194.  
  195. Most compression programmes add a suffix to the compressed file. The UNIX
  196. compress programme adds '-Z'. If a compression programme that you want to use,
  197. uses a different suffix, you can set the system variable 'tar$compress$extension'.
  198.  
  199. When writing a file 'TresImp' to an archive the compress command will expand to:
  200.  
  201.   compress < TresImp > Scrap-Z
  202.  
  203. The %1 parameter is substituted with the file name and %2 is substituted with
  204. the scrap file name.
  205.  
  206. The decompress command, when extracting the file, will expand to:
  207.  
  208.   compress -d < Scrap-Z > TresImp
  209.  
  210. So if you have a compression programme 'squash' and a decompression programme
  211. 'expand', which take two parameters and don't use I/O redirection, set the
  212. variables to:
  213.  
  214.   tar$compress          squash %1 %2
  215.   tar$decompress        expand %1 %2
  216.  
  217. You can also specify absolute paths in these variables, e.g. when the
  218. compression programme is on the RAM disc:
  219.  
  220.   tar$compress          ram:$.compress < %1 > %2
  221.   tar$decompress        ram:$.compress -d < %1 > %2
  222.  
  223. Compressed files are automatically detected when extracting. A verbose listing
  224. of the archive also shows the compression percentage.
  225.  
  226. NOTE: The 'z' option is intended for hard disc backups, so that they can be
  227. compressed while being created. If you are created a normal archive file which
  228. will not be split, it is more efficient to compress the tar archive after
  229. it has been created. To do this, use the compress programme:
  230.  
  231. tar cvf myarc files...
  232. compress myarc
  233.  
  234. You will have to decompress the archive before extracting file form it.
  235.  
  236.  
  237.  
  238. 7. The List File
  239. ----------------
  240. The command:
  241.  
  242. tar l tarlist
  243.  
  244. will read file names and options from the file 'tarlist' instead of the
  245. command line, if any file names are given they will be ignored, options
  246. on the command line are overridden by options specified in the 'tarlist'
  247. file. The 'tarlist' file may contain empty lines, which are ignored, lines
  248. with one file name, and lines starting with a period followed by one
  249. command or option or a blank and a comment. For example:
  250.  
  251.  
  252. . tar archive definition file (this is a comment, note blank after the period)
  253.  
  254. .c create command (stuff after .c is ignored)
  255. .v verbose option (stuff after .v is ignored)
  256. .f :0.backup (archive file name)
  257. .z compress option ( " )
  258. .b 400 blocking factor (stuff after 400 is ignored)
  259.  
  260. . file names follow
  261.  
  262. !Boot
  263. Apps.*
  264. Games.*
  265.  
  266.  
  267. This example file can be found in the distributed tar archive. If no list file
  268. name is given on the command line '!tarlist' will be used as default.
  269.  
  270.  
  271.  
  272. 8. UNIX Compatibility
  273. ---------------------
  274. Another main use of the tar programme is as a file transfer programme between
  275. UNIX and RISC OS. Archives created with the 'U' option can be processed by
  276. UNIX tar programmes. The UNIX file system doesn't know anything about file
  277. types, so these will be lost when using the 'U' option. File permissions and
  278. date stamps are converted to UNIX format (this is always done, even if the
  279. 'U' option is not used, but tar will save the original RISC OS date stamps
  280. also if 'U' is not used. UNIX tar programmes which ignore extra information
  281. in the tar header will be able to process non-UNIX archives).
  282.  
  283. The RISC OS version of tar detects UNIX tar archives and converts file names to
  284. adfs. The 's' option can be used to swap the extension of a file:
  285.  
  286. RISC OS ---> UNIX:  c.test ---> test.c
  287. UNIX ---> RISC OS:  test.c ---> c.test
  288.  
  289. When converting from RISC OS to UNIX, tar will only regard directories as a file
  290. name extension if the directory name is shorter than the maximum file name
  291. extension length. This is 3 by default, but can be set with the 'e' option.
  292.  
  293. The 'Z' option converts the UNIX '.Z' suffix to a '-Z' suffix as used by the
  294. compress programme ( test.c.Z -> c.test-Z ).
  295.  
  296. The 'p' option can be used when creating a UNIX archive to translate a '!' at the
  297. beginning of a file name to '.'.
  298.  
  299. NOTE: UNIX tar archives do not support multiple disc archives! They also do not
  300.       support date stamps which are less than 1-Jan-1970.
  301.  
  302.  
  303.  
  304. 9. Raw disc dumping
  305. -------------------
  306. To transfer files directly via floppy disc to a UNIX machine, you will have to
  307. create a UNIX archive which is dumped on a raw disc, i.d. a disc that is
  308. formatted but which will not contain a directory structure. The most common
  309. disc format is the MS-DOS format (2 sides, 80 tracks, 9 sectors per track).
  310.  
  311. To create a raw disc archive use the special archive name 'floppy:'. Supply
  312. the drive number after the colon. For example:
  313.  
  314. tar cvf floppy:0 files...
  315.  
  316. will create a raw disc archive in drive 0 on a E/D-format disc.
  317.  
  318. tar cvf floppy:0M files...
  319.  
  320. will create a raw disc archive in MS-DOS format.
  321.  
  322. Disc should be formatted before dumping an archive on them.
  323.  
  324. On a UNIX machine a typical command to extract an archive from floppy disc
  325. could be:
  326.  
  327. tar xvf /dev/rfd0
  328.  
  329.  
  330.  
  331. 10. History
  332. -----------
  333.  
  334. 1.1o:
  335.   - Acorn tar file type &C46 is now used by default
  336.   - exit code is now 0 not 22 when writing archive
  337.   - tar sprite now for file type &C46
  338.  
  339. 1.1n
  340.   - extensions were not truncated when extracting from unix archives
  341.   - tar file type is now always used
  342.   - simple tar file sprite included in the distribution
  343.  
  344. 1.1m
  345.   - severe mess-up when truncating long unix path names corrected,
  346.     first file with directories in name which had to be created was not extracted!
  347.  
  348. 1.1l
  349.   - new 'X' option, add textual file type as extension in UNIX archives
  350.  
  351. 1.1k
  352.   - formatting is now done with *adfs:format 0 e y
  353.  
  354. 1.1j
  355.   - 'Q' option corrected, options are scanned before startup code
  356.      is performed
  357.  
  358. 1.1i
  359.   - 'T' option now works correctly with file types less than 0x100
  360.  
  361. 1.1h
  362.   - removed problems with startup-dir and archive on separate discs
  363.  
  364. 1.1g
  365.   - limit of 77 files in a directory removed
  366.   - programme now exits with Sys$ReturnCode != 0 on user interrupt
  367.     if writing an archive
  368.  
  369. 1.1f
  370.   - 'Q' option added: non-interactive mode
  371.   - 'T' option added: file type handling like RISC-OS NFS
  372.  
  373. 1.1e
  374.   - "-C" can now also be used when extracting
  375.  
  376. 1.1d
  377.   - 'M' option re-introduced, must be used for multiple disc archiving
  378.   - raw disc dumping now should be chosen with 'f' option and 'floppy:'
  379.     archive name
  380.   - prompt for confirmation when using raw disc archives,
  381.     'O' option disables confirmation
  382.   - improved 'i' option, better defective archive handling
  383.   - when creating UNIX archives, directory to file extension swapping
  384.     will only occur if 's' option is used
  385.   - 'p' option introduced, enables '!' to '.' translation
  386.   - 'F' option introduced, formats floppy in drive 0 to E-format,
  387.     intended for hard-disc backup
  388.   - new system variable tar$compress$extension enables further configuring
  389.     of the compression programme used.
  390.  
  391. 1.1a
  392.   - first release to 'comp.sys.acorn'
  393.     Now I can feel what international means...
  394.     (A tip of the magical hat to all Rush fans)
  395.   - multiple disc archiving changed, now consistent with normal use; archives
  396.     on multiple floppy discs are now ordinary files and are split into
  397.     several files on different discs; main problem was writing a
  398.     filing-system independent free-space routine (not all filing systems are
  399.     FileCore based!)
  400.   - tar$filetype introduced; when set use value as FileType for tar files,
  401.     maybe Acorn could supply a tar file type; this would be mandatory for
  402.     a desktop version
  403.   - dangerous bug with tar$scrap set to directory removed; used to delete
  404.     directory recursively, now produces error message
  405.   - bug when extracting directories 'bad file name' removed
  406.   - tar$scrap now only has to be set when using compression
  407.  
  408. 1.0o
  409.   - RISC OS to UNIX file name conversion introduced
  410.     directory names may be converted to extensions,
  411.     '!' to '.', '/' to '_'
  412.   - new list file default '!tarlist'
  413.   - compress now called with I/O redirection, saves disk space and
  414.     I/O access time
  415.  
  416. 1.0n
  417.   - UNIX/RISC-OS time conversion rewritten: FP eliminated,
  418.     minor deviations corrected, over-/underflow check
  419.   - FSVars module no longer required
  420.  
  421. 1.0l-m
  422.   - system variable for compression scrap file tar$scrap
  423.   - system variables for compression and decompression commands
  424.     tar$compress, tar$decompress
  425.  
  426. 1.0h-i
  427.   - fixed more bugs with 's' option and introduced 'Z' option
  428.  
  429. 1.0g
  430.   - fixed bug with 's' option
  431.  
  432. 1.0f
  433.   - the 'r' option is now implemented
  434.   - the 'L' type discs are now implemented
  435.   - the 'M' option was dropped, multiple disk archives are now default
  436.     expect if writing a UNIX archive, or 'O' option is used
  437.   - new 'l' option introduced, files and options can now be specified
  438.     in a LIST file
  439.   - tar now prompts for 'discs' not 'volumes'
  440.  
  441. 1.0e
  442.   - first release into the public domain in 'eunet.micro.acorn'
  443.